package com.admin_system.service;

import com.admin_system.pojo.User;

/**
 * 用户服务接口
 * 定义了用户管理相关的业务功能
 * 包括用户登录、注册、信息查询和令牌管理等操作
 */
public interface UserService {
    
    /**
     * 通过用户名和密码登录
     * 
     * @param username 用户名
     * @param password 密码（明文）
     * @return 登录成功返回用户对象，失败返回null
     */
    User loginByUsername(String username, String password);
    
    /**
     * 通过手机号和密码登录
     * 
     * @param phone 手机号
     * @param password 密码（明文）
     * @return 登录成功返回用户对象，失败返回null
     */
    User loginByPhone(String phone, String password);

    /**
     * 用户登录，支持通过用户名或手机号登录
     * @param account 用户名或手机号
     * @param password 密码
     * @return 登录成功返回用户对象，失败返回null
     */
    User login(String account, String password);
    
    /**
     * 根据用户名查找用户
     * 用于用户信息查询和身份验证
     * 
     * @param username 用户名
     * @return 用户对象，如果不存在则返回null
     */
    User findByUsername(String username);

    /**
     * 用户注册
     * 创建新用户账户，包括密码加密和初始化用户状态
     * 
     * @param user 包含注册信息的用户对象
     * @throws RuntimeException 如果用户名或手机号已存在
     */
    void register(User user);
    
    /**
     * 检查用户名是否已存在
     * 用于注册验证
     * 
     * @param username 要检查的用户名
     * @return 存在返回true，不存在返回false
     */
    boolean checkUsernameExists(String username);
    
    /**
     * 检查手机号是否已存在
     * 用于注册验证
     * 
     * @param phone 要检查的手机号
     * @return 存在返回true，不存在返回false
     */
    boolean checkPhoneExists(String phone);
    
    /**
     * 检查邮箱是否已存在
     * 用于注册验证和密码找回
     * 
     * @param email 要检查的邮箱
     * @return 存在返回true，不存在返回false
     */
    boolean checkEmailExists(String email);

    /**
     * 获取使用指定邮箱的用户数量
     * @param email 邮箱
     * @return 用户数量
     */
    int getUserCountByEmail(String email);

    /**
     * 更新用户的真实姓名
     * 用于个人资料维护
     * 
     * @param userId 用户ID
     * @param fullName 新的真实姓名
     * @return 更新成功返回true，失败返回false
     */
    boolean updateUserFullName(Integer userId, String fullName);
    
    /**
     * 通过邮箱重置用户密码
     * 用于密码找回功能
     * 
     * @param email 用户邮箱
     * @param newPassword 新密码（明文）
     * @return 重置成功返回true，失败返回false
     */
    boolean resetPasswordByEmail(String email, String newPassword);
    
    /**
     * 生成并保存用户JWT令牌
     * 用于实现无状态认证和授权
     * 
     * @param user 用户对象
     * @return 生成的JWT令牌字符串
     */
    String generateUserToken(User user);
    
    /**
     * 验证用户令牌是否有效
     * 检查令牌的有效性和是否与用户当前令牌匹配
     * 
     * @param username 用户名
     * @param token JWT令牌
     * @return 有效返回true，无效返回false
     */
    boolean validateUserToken(String username, String token);
    
    /**
     * 使用户的所有令牌失效
     * 用于实现登出功能和安全控制
     * 
     * @param username 用户名
     */
    void invalidateUserTokens(String username);

    /**
     * 获取活跃用户总数
     * 统计系统中所有活跃状态的用户数量
     * 
     * @return 活跃用户总数
     */
    int countActiveUsers();
}